% --------------------------
\section{Related work}
Prey-predator simulation is very well know problem in big system simulation and there are
numerous ways to solve this kind of problems. Approaches to model Prey-predator relations are diverse.
Some may use mathematical equations to model groups of agents whereas some might want to modeling
every agent individually and then study the global outcome.
Prey-predator simulation can be seen as a subset of social modeling. For instance technics used in \cite{criminals},
to model Guardians, Criminals and Passer-by in the context of crime-prevention may be used for Prey-predator 
modeling as well. Therefore a lot of studies in the area of social modeling can be seen as related work. 
\\Yet our study mostly stems from ideas developped in \cite{wator}. In this paper, the 
author describes its ``Computer recreations'' that led him to create an ecosystem modeled as a cellular automaton.
This ecosystem takes place on the planet Wa-Tor, completely covered by water, in which co-exists only 2 species:
fishes and sharks. The planet is toroidal, meaning that if a living creature moves down passed the bottom of the world, 
it would reappear at the upper edge. Similarly by rotation and symetry, the same rules apply for the top, left and right 
edges. Both sharks and fish live, move, reproduce and die in Wa-Tor, according to the a certain number of rules. Time passes in discrete 
steps called ``chronons''. Willing to try different strategies for the species, we use \cite{flocks:herds} to derive new behaviors
for species.

% --------------------------
\section{Experimental setup}
The goal of our study is to evaluate different movement startegies for bothe predators and preys
and the effet of different specie parameters on the overall population.
In this section we first describe the Wa-tor world and its rules, then discuss our implementation.
\subsection{The Wa-Tor world}
The simulation world we used in this study is very close to the Wa-tor world described in \cite{wator}.
Still, it contains some differences regarding to the number of species avaiblables and their strategies. Also
the topoly, only available in 2D in the latter paper, becomes available in 3D for our implementation. In the above section we
describe our simulation world and the rules that apply to the agents living in it. Please note that we reuse the name
Wa-Tor for our simulation world although it differs from the original one.

\subsubsection{Simulation overview}
A simulation is composed of rounds. A round can be seen as a unit of time. It has the same meening as the ``chronon'' in \cite{wator}.
Between two rounds, all the agents living in the world will have to make a decision regarding to the next spatial position they wish to
occupy in the world. Each agent will take into account (or not) the agents close to him in the decision process. 

\subsubsection{Common rules for all agents}
The following rules apply to all types of agents in the Wa-Tor world:
\begin{itemize}
 \item All agent of the same specie have a neighborhood radius. An agent can only see other agents if they are whithin their 
neighborhood radius. In other words, an agent can only take into accounts agents in its neighborhood in its movement decision
process.
 \item All agents have a breed time. The breed time is the number of rounds after which the agent can breed. In our 
simulation we assume agent can reproduce alone. As a consequence, if the world only contains one agent, it will still be able 
to reproduce. The breed time could therefore be called duplication time.
\end{itemize}

\subsubsection{Specific rules for predators}
The specific rule following applies to all predators in the Wa-Tor world:
\begin{itemize}
 \item All predators of the same specie have a starve time. It represents the time a predator can survive without eating.
If the starve time is out, the agent simply dies and is removed from the Wa-Tor world.
\end{itemize}
\subsubsection{Possible simulation outcomes}
The balance of this ecosystem is very delicate: the populations of two species can follow hugely different cycles depending on 
the starve time and breed time, as well as starting positions of each agent.
We may go from both species being endangered to an abundance of one or both. In a small way, Wa-Tor simulates what 
really happens in nature, showing the evolution of the population of a species and its natural predator, 
and the bond that binds them.When the prey are numerous, predators can reproduce rapidly.
But this increase in turn increases the number of prey hunted and the population of the prey decreases. 
By becoming rarer prey, predators begin to starve and die of starvation, decreasing their population and 
easing the pressure on hunting prey. The prey can then go back to rapidly reproducing as the cycle repeats itself.\\\\

{\bf Outcome of a single simulation}\\
For the needs of the simulation, we define the three different outcomes described in Figure \ref{outcomes}.
\begin{figure}
\begin{itemize}
 \item \textit{Predators win (outcome 1) } : After the \textit{maximum number of rounds
\footnote{Number of rounds after which a simulation terminates and an outcome is decided.}}, only predators remain
\footnote{One has to note that it is just a partial victory because predator have no interest 
in seing the preys' population eradicated.} or neither preys nor predator remains
\footnote{This is the case where predators ate all preys and then died by starvation}.
\item \textit{Preys win (outcome 2) } : After the \textit{maximum number of rounds}, only prey remains.
\item \textit{Equilibrium (outcome 3) } : After the \textit{maximum number of rounds} both predator and preys remain.
\end{itemize}
\caption{Possible outcomes}
\label{outcomes}
\end{figure}

{\bf Average outcome of several simulations}
\\To estimate the effect of different parameters on simulations, we need to run a lot of simulations
and output an overall outcome over all the simulations. Figure \ref{overall:outcome} define
our rules used to derive a global outcome out of multiple simulation results.

\begin{figure}
\begin{enumerate}
 \item We count the number of outcomes 1,2 and 3 and compute their frequencies.
 \item In order to output outcome 1 or 2, the number 
of occurence of this outcome has to be the majority among all outcomes. For instance, if 10,4,6
is the number of respectively outcome 1 2 and 3, then the overall outcome will be 1. Indeed, the
frequencies of the different outcome are 50\%,20\%,30\%, so outcome 1 has the majority.
 \item If neither outcome 1 nor 2 has the majority, we just output outcome 3.
\end{enumerate}
\caption{Rules to determine overall outcome}
\label{overall:outcome}
\end{figure}

\subsection{Implementation}
Before studying the effect of specie parameters on the different strategies, we had to build
some tools to facilitate the running experiment. Below, we describe the framework used as a
base for our implementation, the graphic user 

\subsubsection{The Wa-Tor framework}
For this project we didn't start from scratch. We used a framework already developped
for Wa-Tor like prey-predator simulation. This framework provides agent abstraction, 
population, topology and strategy abstraction. Only one strategy: the random strategy 
was implementated, so we had to develop new strategies. Also, no convenient user interface
was provided.\\ \textit{{\bf NEED FOR ADDITIONAL REFERENCES !!!}}

\subsubsection{Strategies}
As mentionned previouly, the framework used only came with a random movement strategy.
An important part of our work was to design and implement new strategies, using the 
strategy abstraction provided. The strategies will be described in more details 
later in the paper.

\subsubsection{Wa-Tor graphic user interface}
The first part of our work was to develop a graphic user interface that facilitate setting up
and starting a new simulation. The functionalities of this gui are:
\begin{itemize}
 \item Select species for the simulation.
 \item Setup the parameters for the species (breed and starve stime).
 \item Choose the movement strategy for each specie and change the strategy parameters.
 \item Choose between a 2D or 3D topology.
 \item Start, stop, reset simulations.
 \item Adjust the simulation speed.
 \item Rotate the camera in the case of a 3D topology.
\end{itemize}

\subsubsection{Simulation recorder and viewer}
To be able to plot population-time diagrams\footnote{On the y-axis, the number of agent of one specie, on the x-axis the
number of rounds (or the time), one curv per specie.} we had to develop a module to log the simulation. This module records
for every round the number of each agent selected for the simulation. The names of the different agents are also saved in
the file. The module wil save automatically any simulation initiated through the gui. Additionally, we developped a python script, 
using matplotlib, able to plot the population-time diagrams using the generated file.

\subsubsection{Wa-Tor batch simulation module}
We ultimately wish to output 3D plots showing the distribution of the different outcomes described in Figure \ref{outcomes}
as a function of the specie parameters: predator starvation time, predator breed time and prey breed time.Therefore
for each couple of parameters \((pred_{s},pred_{b},prey_{b})\) within intervals defined by the user,
we run \textit{mumberOfSimulation} simulation and output the overall outcome following rules of Figure \ref{overall:outcome}.
We therefore developped a command-line interface to setup the simulation parameters, the intervals 
for \((pred_{s},pred_{b},prey_{b})\) and start the simulation. The Figure \ref{wator:cli} gives a typical 
example of usage for the command-line interface.In this example,\\\((pred_{s},pred_{b},prey_{b})\) will 
be within \([|1..10|]\times[|1..10|]\times[|1..10|]\) and the iteration step for the three parameters will be 1. 
The command \textit{ls} displays the different species and their information (strategy, population).
The command \textit{start} launches the simulation
while at the same time setting up the intervals for the parameters. The module will save in a file the mapping from 
the simulation parameters to the global outcome.\\
Finally, to display the 3D plots we implemented a python script using matplotlib that reads the result file
outputed by the Wa-Tor cli.

\begin{figure}
\begin{it}
wator-cli>ls \\
wator-cli>select predator Shark\\
wator-cli>select prey Fish\\
wator-cli>set Shark population 10\\
wator-cli>set Fish population 20\\
wator-cli>set Shark strategy Random(5)\\
wator-cli>set Fish strategy InertiaRandom(5,7,3,3)\\
wator-cli>start 1 10 1 10 1 10 1 1 1 \\
wator-cli>start 1 10 1 10 1 10 1 1 1 \\
Number of rounds ?> 400\\
Number of simulations ?> 5\\
Output file prefix ?> mas-report-output\\
\end{it}
\caption{The Wa-Tor cli, usage example.}
\label{wator:cli}
\end{figure}